# Update an existing group channel

Modifies properties of an existing channel. Requires group administrator privileges. Only included fields are updated; null fields preserve existing values. Privacy changes are constrained by the parent group's privacy (cannot make a channel public in a private group). Changes to auto-subscribe status affect auto-follow behavior for new members.

RBAC: requires GroupChannels.Manage

Endpoint: PUT /api/v1/groups/{groupId}/channels/{channelId}
Version: 1.0
Security: header

## Path parameters:

  - `channelId` (string, required)
    The unique identifier of the channel to update
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupId` (string, required)
    The unique identifier of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Query parameters:

  - `htmlContent` (any)
    Returns text as html if true or original text if false. Applicable only to local posts and users. Default is true.

## Request fields (application/json):

  - `displayName` (string,null)
    New display name for the channel. Updates how the channel appears in UI.
    Example: "Group Announcements"

  - `summary` (string,null)
    New channel description (max 1024 characters)
    Example: "Important announcements and updates"

  - `privacy` (string,null)
    New privacy level. Cannot make a channel public if the parent group is private. Changing from public to private affects visibility and access.
    Enum: "PUBLIC", "PRIVATE"

  - `isAutoSubscribe` (boolean,null)
    Whether this channel should be an auto-subscribe channel (auto-followed by new members)
    Example: true

  - `avatarId` (string,null)
    Upload ID for the channel avatar image. Must be a previously uploaded image. Set to null to remove the avatar.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `headerId` (string,null)
    Upload ID for the channel header/banner image. Must be a previously uploaded image. Set to null to remove the header.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `fields` (object,null)
    Channel profile fields (key-value pairs for additional information)

  - `location` (object,null)
    Channel location information

  - `location.geo` (object,null, required)
    Coordinates and other geo data

  - `location.geo.latitude` (number, required)

  - `location.geo.longitude` (number, required)

  - `location.geo.altitude` (number,null)

  - `location.geo.accuracy` (number,null)

  - `location.geo.verticalAccuracy` (number,null)

  - `location.geo.speed` (number,null)

  - `location.geo.bearing` (number,null)

  - `location.geo.timestamp` (integer,null)

  - `location.name` (string,null, required)

  - `location.autoUpdate` (boolean, required)

  - `location.show` (boolean, required)

  - `timezone` (object,null)
    Channel timezone preferences

  - `timezone.ianaTimezone` (string,null, required)

  - `timezone.autoUpdate` (boolean, required)

  - `timezone.show` (boolean, required)

  - `groupUsername` (string,null)
    New group-scoped username (channel slug). Must be unique within the group. Used to generate the channel's scoped username in format 'groupname:channelname'. This is the channel identifier within the group context.
    Example: "news"

  - `globalUsername` (string,null)
    Global username for the channel. Must be unique platform-wide. Only available for public channels in public groups. Null or omitted means no change. To remove the global username, use the dedicated PUT /channels/{channelId}/username endpoint.
    Example: "platform-news"

  - `color` (string,null)
    Theme color for the channel in 6-character HEX format with # prefix
    Example: "#FF5733"

  - `subscribeExistingMembers` (boolean,null)
    When enabling auto-subscribe, whether to subscribe existing members. Only applies when isAutoSubscribe changes to true. Default: true when isAutoSubscribe is true.

## Response 200 fields (application/json):

  - `id` (string, required)
    internal id of this user
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `username` (string, required)
    unique user name
    Example: "john_smith"

  - `domain` (string, required)
    User's domain
    Example: "wlsly1.net"

  - `local` (boolean, required)
    Whether this user is local to this server

  - `displayName` (string, required)
    full name of the user
    Example: "John Smith"

  - `uri` (string, required)
    URI of this user
    Example: "https://wlsly1.net/users/john_smith"

  - `avatar` (object,null)
    User's avatar

  - `avatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `avatar.meta` (object)
    Meta data

  - `avatar.meta.blurhash` (string,null)

  - `avatar.meta.name` (string,null)

  - `avatar.meta.altText` (string,null)

  - `avatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `avatar.files` (array, required)
    List of all the files this upload has

  - `avatar.files.uri` (string,null, required)
    Full url of the file

  - `avatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `avatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `avatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `avatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `avatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `avatar.files.meta.width` (integer,null)
    Media width

  - `avatar.files.meta.height` (integer,null)
    Media height

  - `avatar.files.meta.codec` (string,null)
    Video codec

  - `avatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `avatar.files.size` (integer, required)
    File size in bytes

  - `avatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `avatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `avatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `avatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `avatar.error` (string,null)
    Upload processing error

  - `avatar.cached` (boolean)
    true if cached

  - `avatar.logs` (string,null)
    Logs

  - `avatar.remote` (boolean)
    true if this upload is remote

  - `avatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `avatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `createdAt` (string, required)
    User's creation time
    Example: "2022-03-10T16:15:50Z"

  - `state` (string, required)
    User's moderation state
    Enum: "REGULAR", "SENSITIVE", "LIMITED", "SUSPENDED"

  - `relationship` (object,null)
    Relationship with this user

  - `relationship.following` (string,null)
    Does the viewer follow the target?
    Enum: "PENDING", "ACCEPTED", "REJECTED"

  - `relationship.followed` (string,null)
    Does the target follow the viewer?
    Enum: "PENDING", "ACCEPTED", "REJECTED"

  - `relationship.blocked` (boolean,null)
    Viewer blocked the target

  - `relationship.blockedBy` (boolean,null)
    Target blocked the viewer

  - `relationship.muted` (object,null)
    Viewer mutes the target

  - `relationship.muted.state` (boolean, required)

  - `relationship.muted.expiresAt` (string,null)
    Example: "2022-03-10T16:15:50Z"

  - `relationship.note` (string,null)
    Viewer's private note about the target

  - `entityType` (string)
    Entity type: USER, BOT, APPLICATION, GROUP_CHANNEL
    Enum: "USER", "BOT", "APPLICATION", "GROUP_CHANNEL"

  - `appMeta` (object)
    Structured metadata (channel flags, channel color, etc.)

  - `groupId` (string,null)
    Group ID if this is a group channel or group user.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupPrivacy` (string,null)
    Privacy of this channel in a group.
    Enum: "PUBLIC", "PRIVATE"

  - `groupUserName` (string,null)
    Name of the channel inside a group

  - `actorType` (string,null)
    Whether this user is a person, application or a service
    Enum: "Application", "Group", "Organization", "Person", "Service"

  - `summary` (string, required)
    User's summary or bio
    Example: "Pixels are my paint, code is my canvas, creativity is my brush."

  - `stats` (object)
    User stats

  - `stats.posts` (integer, required)
    Total number of posts

  - `stats.postsLast24h` (integer, required)
    Posts created in the last 24 hours

  - `stats.totalStorageBytes` (integer, required)
    Total uploaded bytes

  - `stats.comments` (integer, required)
    Total number of comments

  - `stats.avgPostsPerDay` (number, required)
    Average posts per day over the last 30 days

  - `stats.avgBytesPerDay` (number, required)
    Average uploaded bytes per day over the last 30 days

  - `stats.followers` (integer, required)
    number of followers

  - `stats.following` (integer, required)
    number of following

  - `stats.followingHidden` (boolean, required)
    privacy setting to hide followings

  - `stats.totalEvents` (integer, required)
    total number of events (group/user) emitted

  - `fields` (object)
    User fields

  - `header` (object,null)
    User's header

  - `header.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `header.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `header.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `header.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `header.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `header.meta` (object)
    Meta data

  - `header.meta.blurhash` (string,null)

  - `header.meta.name` (string,null)

  - `header.meta.altText` (string,null)

  - `header.size` (integer, required)
    Size in bytes of all the files in this upload

  - `header.files` (array, required)
    List of all the files this upload has

  - `header.files.uri` (string,null, required)
    Full url of the file

  - `header.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `header.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `header.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `header.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `header.files.meta.duration` (number,null)
    Video duration in seconds

  - `header.files.meta.width` (integer,null)
    Media width

  - `header.files.meta.height` (integer,null)
    Media height

  - `header.files.meta.codec` (string,null)
    Video codec

  - `header.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `header.files.size` (integer, required)
    File size in bytes

  - `header.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `header.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `header.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `header.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `header.error` (string,null)
    Upload processing error

  - `header.cached` (boolean)
    true if cached

  - `header.logs` (string,null)
    Logs

  - `header.remote` (boolean)
    true if this upload is remote

  - `header.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `header.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `deleted` (boolean,null)

  - `emojis` (array,null)

  - `emojis.shortcode` (string, required)

  - `emojis.category` (string,null, required)

  - `emojis.url` (string, required)

  - `emojis.staticUrl` (string, required)

  - `emojis.visibleInPicker` (boolean, required)

  - `location` (object,null)
    User's location, geo and name

  - `location.geo` (object,null, required)
    Coordinates and other geo data

  - `location.geo.latitude` (number, required)

  - `location.geo.longitude` (number, required)

  - `location.geo.altitude` (number,null)

  - `location.geo.accuracy` (number,null)

  - `location.geo.verticalAccuracy` (number,null)

  - `location.geo.speed` (number,null)

  - `location.geo.bearing` (number,null)

  - `location.geo.timestamp` (integer,null)

  - `location.name` (string,null, required)

  - `location.autoUpdate` (boolean, required)

  - `location.show` (boolean, required)

  - `timezone` (object,null)
    User's timezone

  - `timezone.ianaTimezone` (string,null, required)

  - `timezone.autoUpdate` (boolean, required)

  - `timezone.show` (boolean, required)

  - `birthday` (object,null)
    User's birthday

  - `birthday.date` (string,null, required)
    Example: "2022-03-10T16:15:50Z"

  - `birthday.show` (string, required)
    Enum: "NONE", "YEAR", "FULL", "DATE"

  - `software` (string, required)
    Software platform type (wellesley, mastodon, threads.net)
    Example: "wellesley"

  - `groupAvatar` (object,null)
    Group avatar (only present for group channels)

  - `groupAvatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupAvatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupAvatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupAvatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupAvatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `groupAvatar.meta` (object)
    Meta data

  - `groupAvatar.meta.blurhash` (string,null)

  - `groupAvatar.meta.name` (string,null)

  - `groupAvatar.meta.altText` (string,null)

  - `groupAvatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `groupAvatar.files` (array, required)
    List of all the files this upload has

  - `groupAvatar.files.uri` (string,null, required)
    Full url of the file

  - `groupAvatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `groupAvatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `groupAvatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `groupAvatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `groupAvatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `groupAvatar.files.meta.width` (integer,null)
    Media width

  - `groupAvatar.files.meta.height` (integer,null)
    Media height

  - `groupAvatar.files.meta.codec` (string,null)
    Video codec

  - `groupAvatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `groupAvatar.files.size` (integer, required)
    File size in bytes

  - `groupAvatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `groupAvatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `groupAvatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `groupAvatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `groupAvatar.error` (string,null)
    Upload processing error

  - `groupAvatar.cached` (boolean)
    true if cached

  - `groupAvatar.logs` (string,null)
    Logs

  - `groupAvatar.remote` (boolean)
    true if this upload is remote

  - `groupAvatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `groupAvatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `groupName` (string,null)
    Group name (only present for group channels)

  - `groupDisplayName` (string,null)
    Group display name (only present for group channels)

  - `syncState` (string,null)
    Sync state for remote users (null for local users). SHALLOW_SYNCED = profile fetched, SYNC_IN_PROGRESS = deep sync running, DEEP_SYNCED = full outbox fetched, DEEP_SYNC_FAILED = deep sync failed
    Enum: "SHALLOW_SYNCED", "SYNC_IN_PROGRESS", "DEEP_SYNCED", "DEEP_SYNC_FAILED"

  - `deepSyncedAt` (string,null)
    When the last deep sync completed (null if never deep-synced)
    Example: "2022-03-10T16:15:50Z"

  - `followApproval` (string, required)
    Follow approval mode: AUTO_APPROVE, MANUALLY_APPROVES, or UNKNOWN
    Enum: "AUTO_APPROVE", "MANUALLY_APPROVES", "UNKNOWN"

  - `groupPrimary` (boolean,null)
    true if this is primary group channel.

  - `groupAutoSubscribe` (boolean,null)
    true if this is auto-subscribe group channel.

  - `channel` (boolean, required)
    Whether this is a channel or a user. Deprecated: use 'entityType' instead.


## Response 400 fields